Retrieve BVN with Biometric API

Objective

The Retrieve BVN with Biometric API retrieves all the necessary details about a user's Bank Verification Number (BVN).

info

The BVN provides each customer of Nigerian banks with a unique identity across the banking industry.

Input

Output

Nigeria BVN

The following user data will be retrieved: Bank Verification Number First name Middle name Last name Date of birth Registration date Enrollment bank code Enrollment branch Gender Local Government Area (LGA) of origin Local Government Area (LGA) of residence Marital status Name on bank card Nationality Primary phone number Residential address State of origin State of residence Photo Email address Account level National Identification Number (NIN) Secondary phone number Title Watchlist status

API Endpoint

retrieveBVNwithBiometric

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the fields required for the API's request body.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
bvn	Nigeria Bank Verification Number of the user	Mandatory	The value must start with a zero	Not Applicable

Sample Request

The following code shows a standard curl request for the API.

curl --location --request POST 'https://zaf.thomas.hyperverge.co/v1/retrieveBVNwithBiometric' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "bvn": "<Enter_the_BVN_Number>"
}'

Success Response Sample

The following is a sample of a success response from the API.

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "detail": "<Returns_the_verification_detail>",
        "response_code": "<Returns_the_response_code>",
        "bvn_data": {
            "bvn": "<Returns_the_bvn>",
            "firstName": "<Returns_the_first_name>",
            "middleName": "<Returns_the_middle_name>",
            "lastName": "<Returns_the_last_name>",
            "dateOfBirth": "<Returns_the_date_of_birth>",
            "registrationDate": "<Returns_the_registration_date>",
            "enrollmentBank": "<Returns_the_enrollment_bank_code>", 
            "enrollmentBranch": "<Returns_the_enrollment_branch>",
            "gender": "<Returns_the_gender>",
            "lgaOfOrigin": "<Returns_the_lga_of_origin>",
            "lgaOfResidence": "<Returns_the_lga_of_residence>",
            "maritalStatus": "<Returns_the_marital_status>",
            "nameOnCard": "<Returns_the_name_on_card>",
            "nationality": "<Returns_the_nationality>",
            "phoneNumber1": "<Returns_the_phone_number1>",
            "residentialAddress": "<Returns_the_residential_address>",
            "stateOfOrigin": "<Returns_the_state_of_origin>",
            "stateOfResidence": "<Returns_the_state_of_residence>",
            "photo": "<Returns_the_photo>",
            "email": "<Returns_the_email>",
            "levelOfAccount": "<Returns_the_level_of_account>",
            "nin": "<Returns_the_nin>",
            "phoneNumber2": "<Returns_the_phone_number2>",
            "title": "<Returns_the_title>",
            "watchListed": "<Returns_the_watchlisted_status>"
        }
    }
}

Success Response Details

Here's the converted table with descriptions for each field in the JSON response:

Parameter	Type	Description
status	string	The status of the request, indicating success or failure.
statusCode	string	The HTTP status code of the request.
result	object	The result object containing detailed information about the verification.
result.detail	string	A message providing more details about the verification result.
result.response_code	string	The response code indicating the specific outcome of the verification process.
result.bvn_data	object	The BVN (Bank Verification Number) data object containing detailed information about the user.
result.bvn_data.bvn	string	The Bank Verification Number of the user.
result.bvn_data.firstName	string	The first name of the user.
result.bvn_data.middleName	string	The middle name of the user.
result.bvn_data.lastName	string	The last name of the user.
result.bvn_data.dateOfBirth	string	The date of birth of the user.
result.bvn_data.registrationDate	string	The date when the user registered their BVN.
result.bvn_data.enrollmentBank	string	The code of the bank where the user enrolled for their BVN.
result.bvn_data.enrollmentBranch	string	The branch of the bank where the user enrolled for their BVN.
result.bvn_data.gender	string	The gender of the user.
result.bvn_data.lgaOfOrigin	string	The Local Government Area (LGA) of origin of the user.
result.bvn_data.lgaOfResidence	string	The Local Government Area (LGA) of residence of the user.
result.bvn_data.maritalStatus	string	The marital status of the user.
result.bvn_data.nameOnCard	string	The name of the user as it appears on their bank card.
result.bvn_data.nationality	string	The nationality of the user.
result.bvn_data.phoneNumber1	string	The primary phone number of the user.
result.bvn_data.residentialAddress	string	The residential address of the user.
result.bvn_data.stateOfOrigin	string	The state of origin of the user.
result.bvn_data.stateOfResidence	string	The state of residence of the user.
result.bvn_data.photo	string	The photo of the user.
result.bvn_data.email	string	The email address of the user.
result.bvn_data.levelOfAccount	string	The level of the user's bank account.
result.bvn_data.nin	string	The National Identification Number (NIN) of the user.
result.bvn_data.phoneNumber2	string	The secondary phone number of the user.
result.bvn_data.title	string	The title of the user (e.g., Mr., Mrs., Miss).
result.bvn_data.watchListed	string	Indicates whether the user is on a watchlist.

Error Response Samples

The following are some sample error responses from the API.

BVN Required

The following is a sample response for missing BVN.

{
    "status": "failure",
    "statusCode": "400",
    "error": "bvn is required"
}

Missing BVN Input

The following is a sample response for when no input is given.

{
    "status": "failure",
    "statusCode": "400",
    "error": {
        "detail": {
            "number": [
                "This field may not be blank."
            ]
        }
    }
}

Invalid Input Pattern

The following is a sample response when the BVN does not match the required pattern .

{
    "status": "failure",
    "statusCode": "400",
    "error": {
        "detail": {
            "number": [
                "This value does not match the required pattern."
            ]
        }
    }
}

Service Unavailable

The following is a sample response for server downtime .

{
          "status": "failure",
          "statusCode": "503",
          "message": "External vendor downtime",
          "error": "EXTERNAL_DOWNTIME"
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	This value does not match the required pattern	The provided BV does not match the required pattern
400	Input Validation Error: does not meet minimum length of 11	The provided BVN number does not meet the minimum length of 11
401	Missing/Invalid credentials	The appId / appKey is missing or incorrect in the request headers.
403	Access Denied	Please contact Hyperverge
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	Server Busy	Please contact the HyperVerge team for resolution